package com.yunkazaixian.mqtt.service;

import org.eclipse.paho.client.mqttv3.*;
import com.yunkazaixian.mqtt.configuration.MqttMessage;

import java.util.List;
import java.util.concurrent.CompletableFuture;

/**
 * MQTT服务类
 *
 * <p>提供MQTT消息发布和订阅功能的核心服务，封装了底层MQTT客户端操作，
 * 提供简单易用的API供应用程序使用。</p>
 *
 * @author nehc
 * @version 1.0.0
 * @since 2023-04-01
 */
public interface IMqttService {


    /**
     * 初始化方法
     * 在服务启动时订阅默认主题
     */
    public void init();

    /**
     * 销毁方法
     * 在服务关闭时断开MQTT连接
     */
    public void destroy();

    /**
     * 检查客户端连接状态
     *
     * @return 是否已连接
     */
    public boolean isConnected();

    /**
     * 重新连接到MQTT服务器
     *
     * @return 重连操作的CompletableFuture
     */
    public CompletableFuture<Void> reconnect();

    /**
     * 发布消息
     *
     * @param message MQTT消息对象
     * @return 发布操作的CompletableFuture
     */
    public CompletableFuture<Void> publish(MqttMessage message);

    /**
     * 使用单独参数发布消息
     *
     * @param topic   消息主题
     * @param payload 消息内容
     * @return 发布操作的CompletableFuture
     */
    public CompletableFuture<Void> publish(String topic, String payload);

    /**
     * 使用完整参数发布消息
     *
     * @param topic    消息主题
     * @param payload  消息内容
     * @param qos      服务质量
     * @param retained 是否保留
     * @return 发布操作的CompletableFuture
     */
    public CompletableFuture<Void> publish(String topic, String payload, int qos, boolean retained);

    /**
     * 订阅主题
     *
     * @param topic 要订阅的主题
     * @return 订阅成功的主题
     * @throws MqttException MQTT异常
     */
    public String subscribe(String topic) throws MqttException;

    /**
     * 使用指定QoS订阅主题
     *
     * @param topic 要订阅的主题
     * @param qos   服务质量
     * @return 订阅成功的主题
     * @throws MqttException MQTT异常
     */
    public String subscribe(String topic, int qos) throws MqttException;

    /**
     * 批量订阅主题
     *
     * @param topics 要订阅的主题列表
     * @return 订阅成功的主题列表
     * @throws MqttException MQTT异常
     */
    public List<String> subscribe(List<String> topics) throws MqttException;

    /**
     * 取消订阅主题
     *
     * @param topic 要取消订阅的主题
     * @throws MqttException MQTT异常
     */
    public void unsubscribe(String topic) throws MqttException;

    /**
     * 批量取消订阅主题
     *
     * @param topics 要取消订阅的主题列表
     * @throws MqttException MQTT异常
     */
    public void unsubscribe(List<String> topics) throws MqttException;
}
